fix(ai): real endpoints, --agent AI mode, claude auth errors, keyless auto-pick, an isolated claude -p - #850

What and why

A review of forge's AI authoring path (2026-11-06) found five defects, all reproduced on origin/main:

1. LlmConfig.endpoint held the telemetry label litellm://<provider>/<model> whenever no endpoint was set.
   • Ollama sent it to litellm as api_base (litellm://ollama/gemma3:4b), so no local call ever reached the daemon.
   • fluid ai test posted to it and failed with "AI test network error for ollama (UnsupportedProtocol)".
2. fluid forge --agent forced --blank unless a mode flag was given. --agent --llm-provider claude-code --context '<intent>' wrote description: 'TODO: Describe your data product' / sql: SELECT 1 AS placeholder and emitted forge.done exit_code 0, which an IDE agent reads as success.
3. claude -p --output-format json reports a failure on stdout (is_error: true, e.g. "Failed to authenticate: OAuth session expired and could not be refreshed") and leaves stderr empty. The not-authenticated check read stderr only, so users saw "claude-code exited with code 1:" and nothing else.
4. With nothing configured and no TTY, forge fell back to gemini even when a logged-in Claude Code was installed.
5. claude -p ran with Claude Code's full agent prompt plus the user's own hooks, plugins, MCP servers and CLAUDE.md: 47,258 prompt tokens for a one-line call.

Founder decisions:

• --agent honors the AI flags.
• The auto-pick applies only to non-interactive runs, and only after a running local Ollama, so local data never silently moves to the cloud.
• Model defaults are unchanged here, because Command Center passes no --llm-model.
• No backward-compatibility shims.

The change

• 8fa6a051 fix(coding-agent) (3, 5): failures are read from the agent's stdout result. is_error: true fails even at exit code 0, and a login problem raises coding_agent_not_authenticated with the sign-in hint. For claude-code only:

  • the system prompt is replaced with --system-prompt;
  • --tools "", --strict-mcp-config, --setting-sources= (one token, SDK fix(databricks): a contract's sovereignty policy holds for a Databricks expose #778) and --no-session-persistence are added;
  • CLAUDECODE is dropped from the child env (SDK feat(loader): overlays patch builds, exposes and consumes by identity (schema 0.7.6) #732);
  • each flag is passed only when claude --help lists it (probed once per process).

  Pattern from claude-agent-sdk-python (MIT) @ 3cf3446b0f, subprocess_cli.py::_build_command.

• f2aac8ed fix(llm) (1, 4):

  • LlmConfig.endpoint holds only a real address: the stated one, else OLLAMA_HOST, else litellm's own default.
  • OLLAMA_HOST is parsed the way ollama-python's _parse_host (MIT) parses it: a bare host means :11434.
  • Routing calls keep a stated endpoint (endpoint_explicit).
  • fluid ai test probes through the provider call and exits 4 on a 404.
  • Doctor shows "Provider default".
  • Keyless auto-pick, one shared helper for selection, readiness and preflight:
    • Order: a running Ollama, then the first agent CLI on the environment's own PATH (claude-code, codex, cursor, kiro).
    • Blocked by any key or provider key variable, FLUID_LLM_[ROUTING_]ENDPOINT/MODEL, OLLAMA_HOST, a keyring key, a saved provider, --llm-endpoint/--llm-model (and the routing twins), or the agent loop (flag or FLUID_COPILOT_AGENT_LOOP).
    • The litellm preflight lets it through on the base install.
    • Readiness calls an agent ready only when its CLI is on PATH.

• 331f6803 fix(forge) (2): --llm-provider/--llm-model/--llm-endpoint/--context select AI mode under --agent, run non-interactively. AI-mode runs now emit forge.contract_written: the receipt path compared diff_snapshots' create/update against created/modified, so it never fired.

• fadbdbf5: CHANGELOG [Unreleased] (Fixed, Changed).

Review

• Borrow-before-build:

  • claude-agent-sdk-python subprocess_cli.py + CHANGELOG;
  • litellm's Ollama default (llms/ollama/common_utils.py);
  • ollama-python _parse_host.

  Pattern adapted, no new dependency.

• Security review (diff-scoped), 1 finding, fixed and re-checked: a stated --llm-endpoint / --llm-model / FLUID_LLM_* or provider key did not count as configured. A non-interactive run, --agent --llm-endpoint http://onprem-llm.internal:8000/v1 included, therefore sent the prompt to claude-code. The routing endpoint/model variant is closed too.

• Defect scan (diff-scoped, reproduced), 3 P2 + 3 P3, all fixed and re-checked:

  • --agent-loop auto-picking an agent that has no tool use;
  • for_routing() dropping a stated Ollama endpoint;
  • doctor "Ready" for an uninstalled agent;
  • OLLAMA_HOST passing the lean preflight;
  • bare-host port 80;
  • ai test 404 exiting 5.

• Accepted residual: on the base install, a keyring-only key passes the preflight (which reads no keyring by design) and fails cleanly at resolve time.

Testing

• New: tests/test_llm_endpoint_sentinel.py, tests/test_llm_keyless_autopick.py, tests/test_coding_agent_isolation.py, plus additions in test_litellm_absent.py, cli/test_forge_agent_mode.py and test_coding_agent_provider.py.
• Every test file that touches the changed modules: 5945 passed. The 2 failures (tests/cli/test_lazy_core_commands.py) fail the same way on pristine main in a shared venv.
• Lint & Format (ruff, the dead-code sweep, black 24.10.0, product guardrail, detect-secrets), license headers and lint-imports: green.
• fluid --help loads the same 1028 modules on main and on the branch, with none of litellm/httpx/mcp/jsonschema.
• Live, through the fluid CLI:
  • fluid ai test --provider ollama --model qwen3-coder:30b: main ok: false (UnsupportedProtocol); branch ok: true (FLUID_OK) with OLLAMA_HOST unset, localhost and 127.0.0.1:11434.
  • fluid forge --agent --llm-provider ollama --llm-model qwen3-coder:30b --context <intent>: mode ai, valid contract, 107 s.
  • fluid forge --agent --llm-provider claude-code --llm-model sonnet --context <intent>: mode ai, forge.contract_written, a valid contract scoring 10/12 on a fixed fidelity checklist, 57 s, 2 calls, $0.17.
  • claude -p --json-schema with the isolation flags still returns structured_output. The same call went from 47,258 to 1,301 prompt tokens and from 4.2 s to 1.3 s.
• Command Center: fluid forge data-model from-intent ... --llm-provider {openai|anthropic|claude|gemini}, with the key in env and no --llm-model, resolves the same provider, model and routing model as main. Only the endpoint changes, from litellm://… to "".

Documentation

• Docs PR linked:
  • Docs PR: docs(ai): keyless auto-pick, --agent AI mode, an isolated claude -p and the Ollama endpoint (forge-cli#850) forge_docs#204
• No docs needed — this change does not affect user-facing behaviour
• Docs TODO — I know docs are needed and will create a PR in forge_docs before this is merged
  • Pages to update: fluid forge --agent (AI flags select AI mode, forge.contract_written in AI mode), keyless auto-pick for non-interactive runs, claude -p isolation and settings-based Claude auth, fluid ai test exit codes, fluid doctor "Provider default".

Not in this PR

• Stale model defaults (catalog dated 2026-04-24): waits until Command Center passes --llm-model.
• Two pre-existing defects, for a separate PR: non-interactive runs ignore the saved fluid ai setup provider, and --agent stdout mixes rich panels into the JSONL stream.